home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UNIXTOOL / GNU / PERL / PERL5.ZIP / !Perl / Manual / perlsub < prev    next >
Text File  |  1995-04-18  |  8KB  |  191 lines
  1. <!-- $RCSfile$$Revision$$Date$ -->
  2. <!-- $Log$ -->
  3. <HTML>
  4. <TITLE> PERLSUB </TITLE>
  5. <h2>NAME</h2>
  6. perlsub - Perl subroutines
  7. <p><h2>SYNOPSIS</h2>
  8. To declare subroutines:
  9. <p><pre>
  10.         sub NAME;          # A "forward" declaration.
  11.         sub NAME BLOCK # A declaration and a definition.
  12. </pre>
  13. To import subroutines:
  14. <p><pre>
  15.         use PACKAGE qw(NAME1 NAME2 NAME3);
  16. </pre>
  17. To call subroutines:
  18. <p><pre>
  19.         &NAME          # Passes current @_ to subroutine.
  20.         &NAME(LIST);   # Parens required with & form.
  21.         NAME(LIST);        # & is optional with parens.
  22.         NAME LIST;         # Parens optional if predeclared/imported.
  23. </pre>
  24. <h2>DESCRIPTION</h2>
  25. Any arguments passed to the routine come in as array @_, that is
  26. ($_[0], $_[1], ...).  The array @_ is a local array, but its values are
  27. references to the actual scalar parameters.  The return value of the
  28. subroutine is the value of the last expression evaluated, and can be
  29. either an array value or a scalar value.  Alternately, a return
  30. statement may be used to specify the returned value and exit the
  31. subroutine.  To create local variables see the local() and my()
  32. operators.
  33. <p>A subroutine may called using the "&" prefix.  The "&" is optional in Perl
  34. 5, and so are the parens if the subroutine has been predeclared.
  35. (Note, however, that the "&" is <I>NOT</I> optional when you're just naming the
  36. subroutine, such as when it's used as an argument to defined() or
  37. undef().  Nor is it optional when you want to do an indirect subroutine
  38. call with a subroutine name or reference using the <B>&$subref()</B> or
  39. <B>&{$subref}()</B> constructs.  See 
  40. <A HREF="perlref.html">
  41. the perlref manpage</A>
  42.  for more on that.)
  43. <p>Example:
  44. <p><pre>
  45.         sub MAX {
  46.         my $max = pop(@_);
  47.         foreach $foo (@_) {
  48.             $max = $foo if $max < $foo;
  49.         }
  50.         $max;
  51.         }
  52. </pre>
  53. <pre>
  54.         ...
  55.         $bestday = &MAX($mon,$tue,$wed,$thu,$fri);
  56. </pre>
  57. Example:
  58. <p><pre>
  59.         # get a line, combining continuation lines
  60.         #  that start with whitespace
  61. </pre>
  62. <pre>
  63.         sub get_line {
  64.         $thisline = $lookahead;
  65.         LINE: while ($lookahead = <STDIN>) {
  66.             if ($lookahead =~ /^[ \t]/) {
  67.                 $thisline .= $lookahead;
  68.             }
  69.             else {
  70.                 last LINE;
  71.             }
  72.         }
  73.         $thisline;
  74.         }
  75. </pre>
  76. <pre>
  77.         $lookahead = <STDIN>;     # get first line
  78.         while ($_ = get_line()) {
  79.         ...
  80.         }
  81. </pre>
  82. Use array assignment to a local list to name your formal arguments:
  83. <p><pre>
  84.         sub maybeset {
  85.         my($key, $value) = @_;
  86.         $foo{$key} = $value unless $foo{$key};
  87.         }
  88. </pre>
  89. This also has the effect of turning call-by-reference into
  90. call-by-value, since the assignment copies the values.
  91. <p>Subroutines may be called recursively.  If a subroutine is called using
  92. the "&" form, the argument list is optional.  If omitted, no @_ array is
  93. set up for the subroutine; the @_ array at the time of the call is
  94. visible to subroutine instead.
  95. <p><pre>
  96.         &foo(1,2,3);        # pass three arguments
  97.         foo(1,2,3);             # the same
  98. </pre>
  99. <pre>
  100.         foo();          # pass a null list
  101.         &foo();             # the same
  102.         &foo;               # pass no arguments--more efficient
  103. </pre>
  104. <h3>Passing Symbol Table Entries</h3>
  105. [Note:  The mechanism described in this section works fine in Perl 5, but
  106. the new reference mechanism is generally easier to work with.  See 
  107. <A HREF="perlref.html">
  108. the perlref manpage</A>
  109. .]
  110. <p>Sometimes you don't want to pass the value of an array to a subroutine
  111. but rather the name of it, so that the subroutine can modify the global
  112. copy of it rather than working with a local copy.  In perl you can
  113. refer to all the objects of a particular name by prefixing the name
  114. with a star: <B>*foo</B>.  This is often known as a "type glob", since the
  115. star on the front can be thought of as a wildcard match for all the
  116. funny prefix characters on variables and subroutines and such.
  117. <p>When evaluated, the type glob produces a scalar value that represents
  118. all the objects of that name, including any filehandle, format or
  119. subroutine.  When assigned to, it causes the name mentioned to refer to
  120. whatever "*" value was assigned to it.  Example:
  121. <p><pre>
  122.         sub doubleary {
  123.         local(*someary) = @_;
  124.         foreach $elem (@someary) {
  125.             $elem *= 2;
  126.         }
  127.         }
  128.         doubleary(*foo);
  129.         doubleary(*bar);
  130. </pre>
  131. Note that scalars are already passed by reference, so you can modify
  132. scalar arguments without using this mechanism by referring explicitly
  133. to $_[0] etc.  You can modify all the elements of an array by passing
  134. all the elements as scalars, but you have to use the * mechanism (or
  135. the equivalent reference mechanism) to push, pop or change the size of
  136. an array.  It will certainly be faster to pass the typeglob (or reference).
  137. <p>Even if you don't want to modify an array, this mechanism is useful for
  138. passing multiple arrays in a single LIST, since normally the LIST
  139. mechanism will merge all the array values so that you can't extract out
  140. the individual arrays.
  141. <p><h3>Overriding builtin functions</h3>
  142. Many builtin functions may be overridden, though this should only be
  143. tried occasionally and for good reason.  Typically this might be
  144. done by a package attempting to emulate missing builtin functionality
  145. on a non-Unix system.
  146. <p>Overriding may only be done by importing the name from a
  147. module--ordinary predeclaration isn't good enough.  However, the
  148. <B>subs</B> pragma (compiler directive) lets you, in effect, predeclare subs
  149. via the import syntax, and these names may then override the builtin ones:
  150. <p><pre>
  151.         use subs 'chdir', 'chroot', 'chmod', 'chown';
  152.         chdir $somewhere;
  153.         sub chdir { ... }
  154. </pre>
  155. Library modules should not in general export builtin names like "open"
  156. or "chdir" as part of their default @EXPORT list, since these may
  157. sneak into someone else's namespace and change the semantics unexpectedly.
  158. Instead, if the module adds the name to the @EXPORT_OK list, then it's
  159. possible for a user to import the name explicitly, but not implicitly.
  160. That is, they could say
  161. <p><pre>
  162.         use Module 'open';
  163. </pre>
  164. and it would import the open override, but if they said
  165. <p><pre>
  166.         use Module;
  167. </pre>
  168. they would get the default imports without the overrides.
  169. <p><h3>Autoloading</h3>
  170. If you call a subroutine that is undefined, you would ordinarily get an
  171. immediate fatal error complaining that the subroutine doesn't exist.
  172. (Likewise for subroutines being used as methods, when the method
  173. doesn't exist in any of the base classes of the class package.) If,
  174. however, there is an <B>AUTOLOAD</B> subroutine defined in the package or
  175. packages that were searched for the original subroutine, then that
  176. <B>AUTOLOAD</B> subroutine is called with the arguments that would have been
  177. passed to the original subroutine.  The fully qualified name of the
  178. original subroutine magically appears in the $AUTOLOAD variable in the
  179. same package as the <B>AUTOLOAD</B> routine.  The name is not passed as an
  180. ordinary argument because, er, well, just because, that's why...
  181. <p>Most <B>AUTOLOAD</B> routines will load in a definition for the subroutine in
  182. question using eval, and then execute that subroutine using a special
  183. form of "goto" that erases the stack frame of the <B>AUTOLOAD</B> routine
  184. without a trace.  (See the standard <B>AutoLoader</B> module, for example.)
  185. But an <B>AUTOLOAD</B> routine can also just emulate the routine and never
  186. define it.  A good example of this is the standard Shell module, which
  187. can treat undefined subroutine calls as calls to Unix programs.
  188. <p>There are mechanisms available for modules to help them split themselves
  189. up into autoloadable files to be used with the standard AutoLoader module.
  190. See the document on extensions.
  191. <p>